home *** CD-ROM | disk | FTP | other *** search
/ DS-CD ROM 2 1993 August / DS CD-ROM 2.Ausgabe (August 1993).iso / programm / ds0257 / doc.exe / MSTACK.DOC < prev    next >
Text File  |  1992-02-11  |  10KB  |  251 lines
  1.   ─────────────────────────────────────────────────────────────────────────────
  2.   Dokumentation zur Datei: MSTACK.INC
  3.  
  4.   ─────────────────────────────────────────────────────────────────────────────
  5.    
  6.     MSTACK.INC   - Routinen zur Verwaltung eines meldungsorientierten Stacks
  7.                    (für den Assembler A86)
  8.    
  9.                    (c) Bernd Schemmer 1992
  10.                    Letzter Update: 02.02.1992
  11.    
  12.    
  13.     ■ Beschreibung:
  14.     ---------------
  15.     MSTACK.INC stellt Routinen zur Verwaltung eines meldungsorientierten
  16.     Stacks zur Verfügung. Ein Stack (oder auf deutsch: Stapel) ist eine
  17.     nach dem LIFO-Prinzip (Last in, First out) organisierte Datenstruktur
  18.     zur Speicherung von Daten, in diesem Fall von Meldungen, wobei der
  19.     Inhalt der 'Meldungen' für die Routinen völlig unerheblich ist.
  20.    
  21.     Jede Meldung belegt n Byte plus 1 Byte für die Verwaltungsstrukturen,
  22.     wobei n ein Wert im Intervall zwischen 0 und 255 ist.
  23.    
  24.     Die Größe eines Stacks, der durch diese Routinen verwaltet werden
  25.     soll, muß zwischen 256 und 65.535 Byte liegen.
  26.    
  27.     Jeder Stack beginnt immer mit einem 16 Byte großem Header auf einer
  28.     Segment-Grenze.
  29.    
  30.     Die Routinen unterstützen auch die Einteilung von Meldungen in bis
  31.     zu 256 Klassen.
  32.    
  33.     Jeder Stack ist durch einen Semaphor vor gleichzeitiger Bearbeitung
  34.     durch mehrere Prozesse geschützt, wodurch der Stack auch durch
  35.     mehrere verschiedene Prozesse gefüllt und geleert werden kann.
  36.    
  37.     Es ist auch möglich, einen Stack in eine Datei zu sichern und später
  38.     wieder zu laden, da die Routinen nur mit relativen Offsets arbeiten.
  39.     Es muß nur der benutzte Teil des Stacks gesichert werden.
  40.    
  41.    
  42.     ■ Variablen:
  43.     ------------
  44.     MStackSeg             - Word, Segment des aktuellen Stacks
  45.    
  46.          Alle Routinen (außer InitMStack) definieren einen zusätzlichen
  47.          Einsprungpunkt 'name_A'. (z.B. für 'ReadMStack' ist dies
  48.          'ReadMStack_A'). Falls die Routinen über diesen Einsprungpunkt
  49.          aufgerufen werden, arbeiten sie mit dem Stack, dessen Segment
  50.          in dieser Variable gespeichert ist. (Der Wert des Registers ES
  51.          beim Aufruf ist in diesen Fall ohne Bedeutung, das Register ES
  52.          wird aber NICHT gesichert.) Die Variable muß in diesem Fall
  53.          vorher auf einen korrekten Wert gesetzt worden sein! (durch
  54.          den Aufruf von 'InitMStack' oder durch direktes Setzen)
  55.          Falls die Routinen über den normalen Einsprungpunkt aufgerufen
  56.          werden, wird diese Variable weder genutzt noch verändert.
  57.    
  58.     MStackSeg:[MStackUserData1] - Word, für Benutzerzwecke reserviert
  59.     MStackSeg:[MStackUserData2] - Word, für Benutzerzwecke reserviert
  60.    
  61.          An den Offsets MStackUserData1 und MStackUserData2 im Header
  62.          des Stacks sind jeweils 2 Byte (= 1 Wort) für Daten des Programms
  63.          reserviert. Diese beiden Wörter werden von den Routinen zur
  64.          Verwaltung des Stacks weder gelesen noch verändert (also auch
  65.          nicht mit einem definierten Wert initialisiert).
  66.          (MStackUserData1 und MStackUserData2 sind über 'dw' definiert)
  67.    
  68.    
  69.     Alle anderen Variablen zur Verwaltung des Stacks werden im Speicher-
  70.     bereich für den Stack angelegt und sollten von anderen Routinen weder
  71.     gelesen noch verändert werden.
  72.    
  73.    
  74.     ■ Routinen:
  75.     -----------
  76.     InitMStack             - Initialisert (d.h. löscht) den Stack
  77.     LockMStack             - Sperrt einen Stack
  78.     UnLockMStack           - Gibt einen Stack wieder frei
  79.     DeleteMStack           - Löscht den gesamten Stack
  80.     WriteMStack            - Sichert eine neue Meldung auf den Stack
  81.     LookMStack             - Ermittelt die Länge und die Klasse der
  82.                              nächsten Meldung vom Stack
  83.     ReadMStack             - Holt die nächste Meldung vom Stack
  84.     GetMStackStatistik     - Ermittelt die Daten des Stacks
  85.    
  86.     Da alle Variablen zur Verwaltung des Stacks im Segment des Stacks
  87.     angelegt werden, können die Routinen auch mit mehreren Stacks
  88.     gleichzeitig arbeiten.
  89.    
  90.     Hinweis: Da nicht alle verwendeten Namen und Bezeichner dieser Datei
  91.              dokumentiert sind, sollten bei Nutzung dieser Routinen in
  92.              den anderen Quelltexten keine Namen oder Bezeichner, die
  93.              die Zeichenkette 'MStack' enthalten, verwendet werden.
  94.    
  95.    
  96.    
  97.     ■ Fehlernummern der Routinen
  98.     ----------------------------
  99.    
  100.     Alle Fehlernummern der Routinen haben das Format 85xx, wobei xx die
  101.     Nummer des eigentlichen Fehlers ist.
  102.    
  103.     Name                   Nummer   Bedeutung
  104.     ----------------------------------------------------------------------
  105.     MStackIsEmpty      EQU 08501h ; Es ist keine Meldung auf dem Stack
  106.    
  107.     MStackIsFull       EQU 08502h ; Es ist nicht mehr genügend freier Speicher
  108.                                   ; zur Aufnahme der neuen Meldung auf den
  109.                                   ; Stack vorhanden
  110.    
  111.     MStackLengthError  EQU 08503h ; falsche Größe für den Stack angegeben
  112.    
  113.     MStackBufferError  EQU 08504h ; Puffer ist für die nächste Meldung zu
  114.                                   ; klein
  115.    
  116.     MStackMessageError EQU 08205h ; Die Meldung ist zu lang
  117.    
  118.     MStackAktivError   EQU 082FFh ; gleichzeigtiger Zugriff von mehreren
  119.                                   ; Prozessen auf einen Stack nicht möglich
  120.    
  121.    
  122.     ----------------------------
  123.     InitMStack
  124.    
  125.     Funktion: Initialisiert den Stack
  126.    
  127.     Eingabe:  ES = Segment für den Stack
  128.                    Der Stack beginnt immer am Offset 0
  129.               CX = Größe des Speicherbereichs in Byte für den Stack
  130.                    Es muß gelten: 256 < CX < 65.535
  131.    
  132.     Ausgabe:  CF = 0 ->> okay
  133.                          CX = freier Speicher auf dem Stack
  134.               CF = 1 ->> Fehler
  135.                          AX = Fehlernummer
  136.                          Der Stack wurde NICHT eingerichtet.
  137.    
  138.     Bes.:     Das Segment des Stacks wird, falls kein Fehler auftritt, in
  139.               der Variablen MStackSeg gespeichert.
  140.               Der Wert des Semaphors des Stacks wird NICHT berücksichtigt!
  141.    
  142.     ----------------------------
  143.     DeleteMStack
  144.    
  145.     Funktion: Löscht den gesamten Stack
  146.    
  147.     Eingabe:  ES = Segment des Stacks
  148.    
  149.     Ausgabe:  CF = 0 ->> okay
  150.                          CX = freier Speicher auf dem Stack
  151.               CF = 1 ->> Fehler
  152.                          AX = Fehlernummer
  153.    
  154.     ----------------------------
  155.     LockMStack
  156.    
  157.     Funktion: Sperrt einen Stack
  158.    
  159.     Eingabe:  ES = Segment des Stacks
  160.    
  161.     Ausgabe:  CF = 0 ->> okay
  162.               CF = 1 ->> Fehler
  163.                          AX = Fehlernummer
  164.    
  165.     ----------------------------
  166.     UnLockMStack
  167.    
  168.     Funktion: Gibt einen Stack wieder frei
  169.    
  170.     Eingabe:  ES = Segment des Stacks
  171.    
  172.     Ausgabe:  CF = 0 ->> okay
  173.               CF = 1 ->> Fehler
  174.                          AX = Fehlernummer
  175.    
  176.     Bes.:     Der Wert des Semaphors des Stacks wird NICHT berücksichtigt!
  177.    
  178.     ----------------------------
  179.     GetMStackStatistik
  180.    
  181.     Funktion: Ermittelt die statistischen Daten des Stacks
  182.    
  183.     Eingabe:  ES = Segment des Stacks
  184.    
  185.     Ausgabe:  CF = 0 ->> okay
  186.                          CX = freier Speicher auf dem Stack
  187.                          DX = Größe des Stacks
  188.                          AX = Anzahl der Meldungen auf dem Stack
  189.                          BX = Länge des belegten Teils des Stacks
  190.               CF = 1 ->> Fehler
  191.                          AX = Fehlernummer
  192.    
  193.     ----------------------------
  194.     WriteMStack
  195.    
  196.     Funktion: Sichert eine Meldung auf den Stack
  197.    
  198.     Eingabe:  ES = Segment des Stacks
  199.               CX = Länge der Meldung
  200.               DS:SI -> Meldung
  201.    
  202.     Ausgabe:  CF = 0 ->> okay
  203.               CF = 1 ->> Fehler
  204.                          AX = Fehlernummer
  205.                          und falls AX = MStackIsFull ist:
  206.                          CX = max. Länge einer weiteren Meldung für den Stack
  207.                               falls CX = -1 ->> keine weitere Meldung möglich
  208.    
  209.     Bes.:     Das Directionflag wird gelöscht.
  210.    
  211.     ----------------------------
  212.     LookMStack
  213.    
  214.     Funktion: Ermittelt die Daten der nächsten Meldung auf dem Stack
  215.    
  216.     Eingabe:  ES = Segment des Stacks
  217.    
  218.     Ausgabe:  CF = 0 ->> okay
  219.                          CX = Länge der nächsten Meldung
  220.                          und falls CX <> 0:
  221.                          AL = 1. Byte der Meldung
  222.               CF = 1 ->> Fehler
  223.                          AX = Fehlernummer
  224.    
  225.     Bes.:     Die Klasse von Meldungen kann im 1. Byte einer Meldung
  226.               gesichert werden, da dieses Byte auch durch den Look-
  227.               Ahead-Aufruf zurückgeliefert wird.
  228.               Das Directionflag wird gelöscht.
  229.    
  230.     ----------------------------
  231.     ReadMStack
  232.    
  233.     Funktion: Holt die nächste Meldung vom Stack
  234.    
  235.     Eingabe:  ES = Segment des Stacks
  236.               CX = Länge des Puffers für die Meldung
  237.               DS:SI -> Puffer für die Meldung
  238.    
  239.     Ausgabe:  CF = 0 ->> okay
  240.                          Meldung steht im Puffer bei DS:SI
  241.                          CX = Länge der Meldung
  242.               CF = 1 ->> Fehler
  243.                          AX = Fehlernummer
  244.    
  245.     Bes.:     Falls diese Routine mit CX = 0 aufgerufen wird, verhält
  246.               sie sich wie die Routine 'LookMStack'.
  247.               Falls der Puffer bei DS:SI für die Meldung zu klein ist,
  248.               wird die Meldung NICHT vom Stack entfernt.
  249.               Das Directionflag wird gelöscht.
  250.    
  251.